<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Adapters for Zend_Translate - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.translate.adapter.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.translate.adapter.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.translate.introduction.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.translate.html">Zend_Translate</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.translate.using.html">Using Translation Adapters</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.translate.adapter" class="section"><div class="info"><h1 class="title">Adapters for Zend_Translate</h1></div>
    

    <p class="para">
        <span class="classname">Zend_Translate</span> can handle different adapters for translation.
        Each adapter has its own advantages and disadvantages.
        Below is a comprehensive list of all supported adapters for
        translation source files.
    </p>

    <table id="zend.translate.adapter.table" class="doctable table"><div class="info"><caption><b>Adapters for Zend_Translate</b></caption></div>
        

        
            <thead valign="middle">
                <tr valign="middle">
                    <th>Adapter</th>
                    <th>Description</th>
                    <th>Usage</th>
                </tr>

            </thead>


            <tbody valign="middle" class="tbody">
                <tr valign="middle">
                    <td align="left">Array</td>
                    <td align="left">Use <acronym class="acronym">PHP</acronym> arrays</td>
                    <td align="left">Small pages; simplest usage; only for programmers</td>
                </tr>


                <tr valign="middle">
                    <td align="left">Csv</td>
                    <td align="left">Use comma separated (*.csv/*.txt) files</td>

                    <td align="left">
                        Simple text file format; fast; possible problems with unicode characters
                    </td>
                </tr>


                <tr valign="middle">
                    <td align="left">Gettext</td>
                    <td align="left">Use binary gettext (*.mo) files</td>
                    <td align="left">GNU standard for linux; thread-safe; needs tools for translation</td>
                </tr>


                <tr valign="middle">
                    <td align="left">Ini</td>
                    <td align="left">Use simple <acronym class="acronym">INI</acronym> (*.ini) files</td>

                    <td align="left">
                        Simple text file format; fast; possible problems with unicode characters
                    </td>
                </tr>


                <tr valign="middle">
                    <td align="left">Tbx</td>
                    <td align="left">Use termbase exchange (*.tbx/*.xml) files</td>

                    <td align="left">
                        Industry standard for inter application terminology strings;
                        <acronym class="acronym">XML</acronym> format
                    </td>
                </tr>


                <tr valign="middle">
                    <td align="left">Tmx</td>
                    <td align="left">Use tmx (*.tmx/*.xml) files</td>

                    <td align="left">
                        Industry standard for inter application translation; <acronym class="acronym">XML</acronym>
                        format; human readable
                    </td>
                </tr>


                <tr valign="middle">
                    <td align="left">Qt</td>
                    <td align="left">Use qt linguist (*.ts) files</td>

                    <td align="left">
                        Cross platform application framework; <acronym class="acronym">XML</acronym> format; human
                        readable
                    </td>
                </tr>


                <tr valign="middle">
                    <td align="left">Xliff</td>
                    <td align="left">Use xliff (*.xliff/*.xml) files</td>

                    <td align="left">
                        A simpler format as <b><tt>TMX</tt></b> but related to it;
                        <acronym class="acronym">XML</acronym> format; human readable
                    </td>
                </tr>


                <tr valign="middle">
                    <td align="left">XmlTm</td>
                    <td align="left">Use xmltm (*.xml) files</td>

                    <td align="left">
                        Industry standard for <acronym class="acronym">XML</acronym> document translation memory;
                        <acronym class="acronym">XML</acronym> format; human readable
                    </td>
                </tr>


                <tr valign="middle">
                    <td align="left">Others</td>
                    <td align="left">*.sql</td>
                    <td align="left">Different other adapters may be implemented in the future</td>
                </tr>

            </tbody>
        
    </table>


    <div class="section" id="zend.translate.adapter.decision"><div class="info"><h1 class="title">How to decide which translation adapter to use</h1></div>
        

        <p class="para">
            You should decide which Adapter you want to use for
            <span class="classname">Zend_Translate</span>. Frequently, external criteria such as a project
            requirement or a customer requirement determines this for you, but if you are in
            the position to do this yourself, the following hints may simplify
            your decision.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                When deciding your adapter you should also be aware of the used
                encoding. Even if Zend Framework declares UTF-8 as default
                encoding you will sometimes be in the need of other encoding.
                <span class="classname">Zend_Translate</span> will not change any encoding which is defined
                within the source file which means that if your Gettext source
                is build upon ISO-8859-1 it will also return strings in this encoding
                without converting them. There is only one restriction:
            </p>

            <p class="para">
                When you use a <acronym class="acronym">XML</acronym> based source format like TMX or XLIFF you must
                define the encoding within the <acronym class="acronym">XML</acronym> files header because
                <acronym class="acronym">XML</acronym> files without defined encoding will be treated as UTF-8 by
                any <acronym class="acronym">XML</acronym> parser by default. You should also be aware that actually
                the encoding of <acronym class="acronym">XML</acronym> files is limited to the encodings supported
                by <acronym class="acronym">PHP</acronym> which are UTF-8, ISO-8859-1 and US-ASCII.
            </p>
        </p></blockquote>

        <div class="section" id="zend.translate.adapter.array"><div class="info"><h1 class="title">Zend_Translate_Adapter_Array</h1></div>
            

            <p class="para">
                The Array Adapter is the Adapter which is simplest to use for
                programmers.
                But when you have numerous translation strings or many
                languages you should think about another Adapter.
                For example, if you have 5000 translation strings,
                the Array Adapter is possibly not the best choice for you.
            </p>

            <p class="para">
                You should only use this Adapter for small sites with a handful
                of languages, and if you or your programmer team creates the
                translations yourselves.
            </p>
        </div>

        <div class="section" id="zend.translate.adapter.csv"><div class="info"><h1 class="title">Zend_Translate_Adapter_Csv</h1></div>
            

            <p class="para">
                The Csv Adapter is the Adapter which is simplest to use for
                customers.
                CSV files are readable by standard text editors, but
                text editors often do not support utf8 character sets.
            </p>

            <p class="para">
                You should only use this Adapter if your customer wants to do
                translations himself.
            </p>

            <blockquote class="note"><p><b class="note">Note</b>: 
                <p class="para">
                    Beware that the Csv Adapter has problems when your Csv files are encoded
                    differently than the locale setting of your environment. This is due to a Bug of
                    <acronym class="acronym">PHP</acronym> itself which will not be fixed before
                    <acronym class="acronym">PHP</acronym> 6.0 (http://bugs.php.net/bug.php?id=38471). So you should
                    be aware that the Csv Adapter due to <acronym class="acronym">PHP</acronym> restrictions is not
                    locale aware.
                </p>
            </p></blockquote>
        </div>

        <div class="section" id="zend.translate.adapter.gettext"><div class="info"><h1 class="title">Zend_Translate_Adapter_Gettext</h1></div>
            

            <p class="para">
                The Gettext Adapter is the Adapter which is used most
                frequently. Gettext is a translation source format which was
                introduced by GNU, and is now used worldwide.
                It is not human readable, but there are several freeware tools
                (for instance, <a href="http://sourceforge.net/projects/poedit/" class="link external">&raquo; POEdit</a>),
                which are very helpful. The <span class="classname">Zend_Translate</span> Gettext Adapter is
                not implemented using <acronym class="acronym">PHP</acronym>&#039;s gettext extension.
                You can use the Gettext Adapter even if you do not have
                the <acronym class="acronym">PHP</acronym> gettext extension installed.
                Also the Adapter is thread-safe and the <acronym class="acronym">PHP</acronym> gettext extension
                is currently not thread-safe.
            </p>

            <p class="para">
                Most people will use this adapter.
                With the available tools, professional translation is
                very simple. But gettext data are is stored in a
                machine-readable format, which is not readable without tools.
            </p>
        </div>

        <div class="section" id="zend.translate.adapter.ini"><div class="info"><h1 class="title">Zend_Translate_Adapter_Ini</h1></div>
            

            <p class="para">
                The Ini Adapter is a very simple Adapter which can even be used
                directly by customers.
                <acronym class="acronym">INI</acronym> files are readable by standard text editors, but
                text editors often do not support utf8 character sets.
            </p>

            <p class="para">
                You should only use this Adapter when your customer wants to do translations
                himself. Do not use this adapter as generic translation source.
            </p>

            <div class="warning"><b class="warning">Warning</b><div class="info"><h1 class="title">Regression in PHP 5.3</h1></div>
                

                <p class="para">
                    Prior to <acronym class="acronym">PHP</acronym> 5.3,  <span class="methodname">parse_ini_file()</span>
                    and  <span class="methodname">parse_ini_string()</span> handled non-ASCII characters
                    within <acronym class="acronym">INI</acronym> option keys worked without an issue. However,
                    starting with <acronym class="acronym">PHP</acronym> 5.3, any such keys will now be silently
                    dropped in the returned array from either function. If you had keys utilizing
                    UTF-8 or Latin-1 characters, you may find your translations no longer work when
                    using the <acronym class="acronym">INI</acronym> adapter. If this is the case, we recommend
                    utilizing a different adapter.
                </p>
            </div>
        </div>

        <div class="section" id="zend.translate.adapter.tbx"><div class="info"><h1 class="title">Zend_Translate_Adapter_Tbx</h1></div>
            

            <p class="para">
                The Tbx Adapter is an Adapter which will be used by customers
                which already use the TBX format for their internal translation
                system. Tbx is no standard translation format but more a collection
                of already translated and pre translated source strings. When you
                use this adapter you have to be sure that all your needed source
                string are translated.
                TBX is a <acronym class="acronym">XML</acronym> file based format and a completely new format.
                <acronym class="acronym">XML</acronym> files are human-readable, but the parsing is not as fast
                as with gettext files.
            </p>

            <p class="para">
                This adapter is perfect for companies when pre translated
                source files already exist.
                The files are human readable and system-independent.
            </p>
        </div>

        <div class="section" id="zend.translate.adapter.tmx"><div class="info"><h1 class="title">Zend_Translate_Adapter_Tmx</h1></div>
            

            <p class="para">
                The Tmx Adapter is the Adapter which will be used by most
                customers which have multiple systems which use the same
                translation source, or when the translation source must be
                system-independent.
                TMX is a <acronym class="acronym">XML</acronym> file based format, which is announced to be the
                next industry standard.
                <acronym class="acronym">XML</acronym> files are human-readable, but the parsing is not as fast
                as with gettext files.
            </p>

            <p class="para">
                Most medium to large companies use this adapter.
                The files are human readable and system-independent.
            </p>
        </div>

        <div class="section" id="zend.translate.adapter.qt"><div class="info"><h1 class="title">Zend_Translate_Adapter_Qt</h1></div>
            

            <p class="para">
                The Qt Adapter is for all customers which have TS files as their
                translation source which are made by QtLinguist.
                QT is a <acronym class="acronym">XML</acronym> file based format.
                <acronym class="acronym">XML</acronym> files are human-readable, but the parsing is not as fast
                as with gettext files.
            </p>

            <p class="para">
                Several big players have build software upon the QT framework.
                The files are human readable and system-independent.
            </p>
        </div>

        <div class="section" id="zend.translate.adapter.xliff"><div class="info"><h1 class="title">Zend_Translate_Adapter_Xliff</h1></div>
            

            <p class="para">
                The Xliff Adapter is the Adapter which will be used by most customers which
                want to have <acronym class="acronym">XML</acronym> files but do not have tools for TMX.
                XLIFF is a <acronym class="acronym">XML</acronym> file based format, which is related to TMX but
                simpler as it does not support all possibilities of it.
                <acronym class="acronym">XML</acronym> files are human-readable, but the parsing is not as fast
                as with gettext files.
            </p>

            <p class="para">
                Most medium companies use this adapter.
                The files are human readable and system-independent.
            </p>
        </div>

        <div class="section" id="zend.translate.adapter.xmltm"><div class="info"><h1 class="title">Zend_Translate_Adapter_XmlTm</h1></div>
            

            <p class="para">
                The XmlTm Adapter is the Adapter which will be used by customers
                which do their layout themself. XmlTm is a format which allows the
                complete <acronym class="acronym">HTML</acronym> source to be included in the translation source, so
                the translation is coupled with the layout.
                XLIFF is a <acronym class="acronym">XML</acronym> file based format, which is related to XLIFF but
                its not as simple to read.
            </p>

            <p class="para">
                This adapter should only be used when source files already exist.
                The files are human readable and system-independent.
            </p>
        </div>
    </div>

    <div class="section" id="zend.translate.adapter.selfwritten"><div class="info"><h1 class="title">Integrate self written Adapters</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Translate</span> allows you to integrate and use self written
            Adapter classes. They can be used like the standard Adapter classes which
            are already included within <span class="classname">Zend_Translate</span>.
        </p>

        <p class="para">
            Any adapter class you want to use with <span class="classname">Zend_Translate</span> must be a
            subclass of <span class="classname">Zend_Translate_Adapter</span>.
            <span class="classname">Zend_Translate_Adapter</span> is an abstract class which already defines
            all what is needed for translation. What has to be done by you, is the definition of the
            reader for translation datas.
        </p>

        <p class="para">
            The usage of the prefix &quot;Zend&quot; should be limited to Zend Framework.
            If you extend <span class="classname">Zend_Translate</span> with your own adapter, you should
            name it like &quot;Company_Translate_Adapter_MyFormat&quot;. The following code shows an
            example of how a self written adapter class could be implemented:
        </p>

        <pre class="programlisting brush: php">
try {
    $translate = new Zend_Translate(
        array(
            &#039;adapter&#039; =&gt; &#039;Company_Translate_Adapter_MyFormat&#039;,
            &#039;content&#039; =&gt; &#039;/path/to/translate.xx&#039;,
            &#039;locale&#039;  =&gt; &#039;en&#039;,
            &#039;myoption&#039; =&gt; &#039;myvalue&#039;
        )
    );
} catch (Exception $e) {
    // File not found, no adapter class...
    // General failure
}
</pre>

    </div>

    <div class="section" id="zend.translate.adapter.caching"><div class="info"><h1 class="title">Speedup all Adapters</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Translate</span> allows you use internally
            <span class="classname">Zend_Cache</span> to fasten the loading of translation sources. This
            comes very handy if you use many translation sources or extensive source formats like
            <acronym class="acronym">XML</acronym> based files.
        </p>

        <p class="para">
            To use caching you will just have to give a cache object to the
             <span class="methodname">Zend_Translate::setCache()</span> method. It takes a instance of
            <span class="classname">Zend_Cache</span> as only parameter. Also if you use any adapter direct
            you can use the  <span class="methodname">setCache()</span> method. For convenience there are
            also the static methods  <span class="methodname">getCache()</span>,
             <span class="methodname">hasCache()</span>,  <span class="methodname">clearCache()</span> and
             <span class="methodname">removeCache()</span>.
        </p>

        <pre class="programlisting brush: php">
$cache = Zend_Cache::factory(&#039;Core&#039;,
                             &#039;File&#039;,
                             $frontendOptions,
                             $backendOptions);
Zend_Translate::setCache($cache);
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;/path/to/translate.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;en&#039;
    )
);

// to clear the cache somewhere later in your code
Zend_Translate::clearCache();
</pre>


        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                You must set the cache <em class="emphasis">before</em> you use or initiate
                any adapter or instance of <span class="classname">Zend_Translate</span>. Otherwise your
                translation source will not be cached until you add a new source with the
                 <span class="methodname">addTranslation()</span> method.
            </p>
        </p></blockquote>

        <p class="para">
            When the attached cache supports tagging you can set a own tag string by using the
            option <span class="property">tag</span>. This allows you do delete only the cache from this
            single instance of <span class="classname">Zend_Translate</span>. When you are not using this
            option the default tag <span class="classname">Zend_Translate</span> is used.
        </p>

        <p class="para">
            Using the option <span class="property">tag</span> you must give the used tag to
             <span class="methodname">clearCache()</span> to declare which tag you want to delete.
        </p>

        <pre class="programlisting brush: php">
$cache = Zend_Cache::factory(&#039;Core&#039;,
                             &#039;File&#039;,
                             $frontendOptions,
                             $backendOptions);
Zend_Translate::setCache($cache);
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;/path/to/translate.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;en&#039;,
        &#039;tag&#039;     =&gt; &#039;MyTag&#039;
    )
);

// somewhere later in your code
Zend_Translate::clearCache(&#039;MyTag&#039;);
</pre>

    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.translate.introduction.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.translate.html">Zend_Translate</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.translate.using.html">Using Translation Adapters</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.translate.html">Zend_Translate</a></li>
  <li><a href="zend.translate.introduction.html">Introduction</a></li>
  <li class="active"><a href="zend.translate.adapter.html">Adapters for Zend_Translate</a></li>
  <li><a href="zend.translate.using.html">Using Translation Adapters</a></li>
  <li><a href="zend.translate.sourcecreation.html">Creating source files</a></li>
  <li><a href="zend.translate.additional.html">Additional features for translation</a></li>
  <li><a href="zend.translate.plurals.html">Plural notations for Translation</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>